rbm_input_files(7)
==================

NAME
----
rbm_input_files - rbm input files configuration

DESCRIPTION
-----------

When building a project with rbm, the input can be a git or mercurial
repository from which a tarball will be created and used as input for
your build. In addition or instead of this git or mercurial repository,
it is possible to retrieved files from other sources to use them as
input files.

The following input sources are available:

- a URL which should be used to download the file

- a file resulting from the output of a command

- the value of a config value

- the result of the build of an other project

The file that has been retrieved can be verified with:

- matching a specific sha256 checksum

- a gpg signature file from a specific key or keyring

The input files can be located in the output directory (for the result
of an other project's build), or in the project's directory.


CONFIGURATION
-------------

The configuration of the input files is done in the +input_files+
configuration option. This option is an array of file descriptors.
Each file descriptor is an hash containing some of the following
options:

filename::
        The name of the file that will be fetched. Except when an URL
        or a project is set, this filename is mandatory. If it is not
        set when an URL is set, the basename of the URL is used as a
        filename. If it is not set when a project is set, the project's
        filename option is used. The filename can be the name of a
        directory, in which case all the files from the directory are
        included.

name::
        Optionaly the input_file can have a name. This name is used as
        key in the +input_files_by_name+ option.

content::
        The content of the file.

URL::
        The URL from which to download the file.

exec::
        A command or script to execute to produce the file.

project::
        The name of an other project to build, to create the file. The
        content of the file descriptor is used as options for the build
        of this project. You can add config options such as +version+,
        +git_hash+ or +target+ to configure the build. The build is run
        with an equivalent of 'rbm pkg', so you should define the
        +pkg_type+ option if you want to select the type of build. The
        command line options are not forwarded. The name of the current
        project is available to that other project in the +origin_project+
        option.

target::
        An array defining the build targets for the selected project. If this
        option is not set, the current build target is forwarded. If set,
        this replaces the current targets.

target_append::
        The same as +target+, but instead of replacing the current targets,
        the new targets are appended.

target_prepend::
        The same as +target+, but instead of replacing the current targets,
        the new targets are prepended.

enable::
        The files are enabled by default. If this option is set to
        0, then the file is ignored.

refresh_input::
        By default, if the file is already present, it is not downloaded
        or created again, except when an sha256sum is defined and the
        file present is not matching. If this option is set to a true
        value, the file will be removed and created again on each run,
        except when an sha256sum is defined and the file present is
        matching.

sha256sum::
        The sha256 checksum of the file. The build will fail with an
        error if the file does not match the expected sha256 checksum.

file_gpg_id::
        If this option is set to 1, the file is checked for a gpg
        signature. If it is set to an other non zero value, or an array
        of non zero values, those are expected to be the valid gpg key
        IDs. The +gpg_wrapper+, +gpg_keyring+, +gpg_keyring_dir+,
        +gpg_bin+, +gpg_args+ options can be used to configure the gpg
        check. Those options can be overriden in the file descriptor.

sig_ext::
        An array of file extensions for the gpg signature file. Those
        extensions are used to find the signature file when +file_gpg_id+
        is set. If the signature file is missing but an +URL+ is set,
        the extension is appended to the URL to try to download it. The
        default value for +sig_ext+ is 'gpg', 'asc', 'sig'. The +sig_ext+
        can also be set to a single value.

urlget::
        A command or script to be used to download files from an URL.
        It should use +filename+ as the output filename, and +URL+ as
        the source URL. The default is to use 'wget'.

output_dir::
        By default, the files are searched in the project's directory,
        and its output directory. The generated files are stored in the
        project's output directory. If you want to store and search
        a file in a different directory, you can set the 'output_dir'
        option to a different value.

All those options are templates, and can use other options defined
inside or outside the file descriptor. Their default values can be
defined outside the file descriptor.

Those options can also be defined per target, or per distribution.

Instead of a file descriptor hash, an element of the +input_files+
array can be a string. In that case the string is the name of the option
containing the file descriptor hash. This can be useful when you are
using the same file in multiple projects.

EXAMPLES
--------

In the following example we define the +input_files+ configuration for
the project 'bundle'. This project has two different targets, 'dev' and
'stable', and is using input files from different sources :

- The 'project A' tarball is downloaded from an URL with an known
  sha256sum.

- The 'project B' tarball is downloaded from an URL which is different
  depending on the target. The sha256sum is also different depending on
  the target.

- The 'project C' tarball is downloaded from an URL, and checked using a
  gpg signature.

- The 'project D' tarball is built using rbm. The +git_hash+ used to
  build it is different depending on the target. The git tag gpg
  signature is checked only in the stable target.

----
input_files:
 - filename: project-A.tar.gz
   URL: http://www.project-a.org/project.tar.gz
   sha256sum: 93c4fb2f3d377f41001fe1cf3c806dc9fc926a53dbbf4302838d7ee7c9f17315
 - filename: 'project-B-[% c('project_b_version') %].tar.gz'
   URL: 'http://www.project-b.org/project-b-[% c('project_b_version') %].tar.gz'
   targets:
     dev:
       project_b_version: 0.12
       sha256sum: 5f0ac48598c0a7948bb7da626b0599f121c1365ec53b111b5ba9e9330410fc44
     stable:
       project_b_version: 0.10
       sha256sum: f0f81fbc84992c21bbbcb301c1185ce3d1772f150f57d37530cc9e4b0249a630
 - filename: project-c.tar.gz
   URL: http://www.project-c.org/release-0.1.tar.gz
   file_gpg_id: 1
   gpg_keyring: project-c.gpg
   sig_ext: sig
 - filename: project-D.tar.gz
   project: project_d
   pkg_type: build
   targets:
     dev:
       git_hash: master
     stable:
       git_hash: 2.1
       tag_gpg_id: 1
----


SEE ALSO
--------
link:rbm.html[rbm(1)],
link:rbm_config.html[rbm_config(7)]
